home *** CD-ROM | disk | FTP | other *** search
/ CD Actual 90 / CD Actual 90.iso / Software3D / K-3D / k3d-0.4.2.1 / tutorials / reporting_bugs < prev    next >
Encoding:
Text File  |  2004-07-23  |  6.6 KB  |  41 lines
  1. //javascript
  2.  
  3. Application.CommandNode("/application/ui").Command("tutorialmessage", "Howdy!  This next tutorial will cover some information on how to effectively report any bugs you may encounter while using K-3D ...");
  4. Application.CommandNode("/application/ui").Command("tutorialmessage", "It may seem a little strange to bring-up bug reporting when you're just getting started with K-3D, but we don't want you to worry - we're doing so because K-3D has some unique features that make it incredibly easy to report bugs effectively ... features that don't exist in any other program that we've ever seen, anywhere.");
  5. Application.CommandNode("/application/ui").Command("tutorialmessage", "Before you can appreciate K-3D's features in this area, though, you need to understand what constitutes a good bug report and why ... for a concise, very-well-written paper by Simon Tatham on this topic, double-click the left mouse button on the following link: http://www.chiark.greenend.org.uk/~sgtatham/bugs.html");
  6.  
  7. Application.CommandNode("/application/ui").Command("tutorialmessage", "As you can see from Simon's paper, the main purpose (and the main challenge) in writing bug reports is giving developers enough information to reproduce the problem.  In fact, fixing a bug is usually fairly easy, once you have a set of repeatable steps to reproduce it.");
  8. Application.CommandNode("/application/ui").Command("tutorialmessage", "Unfortunately, human language is inherently poor at communicating the kind of step-by-step detail required to reproduce problems - often, reproducing a problem in a program with a graphical user interface means duplicating precisely everything the user did from the time they started the application.");
  9. Application.CommandNode("/application/ui").Command("tutorialmessage", "This can be frustrating for both users and developers, even when you are conscientiously following Simon's advice.  So, what does K-3D have that sets it apart from the pack?  We call it the \"Black Box Recorder\" ...");
  10. Application.CommandNode("/application/ui").Command("tutorialmessage", "K-3D's Black Box Recorder uses the same technology used to record these tutorials to record all of your interaction with K-3D to a log file.  If you encounter a bug, your Black Box Recorder logs can be shared with the K-3D community, so developers can play-back the logs and reproduce the problem.");
  11. Application.CommandNode("/application/ui").Command("tutorialmessage", "Since the logs recorded by the Black Box Recorder log are normal K-3D scripts, you can examine them in a text editor and play them back yourself to verify that they capture whatever it was that you were doing when the bug manifested itself.");
  12. Application.CommandNode("/application/ui").Command("tutorialmessage", "Enough talk!  Let's see how the Black Box Recorder works ...");
  13.  
  14. while(Application.CommandNode("/application/black_box_recorder"))
  15.     {
  16.         Application.CommandNode("/application/ui").Command("tutorialmessage", "(You already have a Black Box Recorder running - we're going to shut it down before proceeding)");
  17.         Application.CommandNode("/application/black_box_recorder/close").Command("activate", "");
  18.     }
  19.  
  20. Application.CommandNode("/application/ui").Command("tutorialmessage", "We'll open a Black Box Recorder now ... all you have to do is give it a filename in the file dialog that opens.  We recommend using a file named \"blackbox.log\" in your home directory ... be careful not to give it the name of an existing file, as the file contents will be immediately overwritten!");
  21. Application.CommandNode("/application/window/tools_black_box_recorder").Command("activate", "");
  22. Application.CommandNode("/application/ui").Command("tutorialmessage", "As you can see, the Black Box Recorder is now open and recording ...");
  23. Application.CommandNode("/application/black_box_recorder").Command("highlight", "");
  24. Application.CommandNode("/application/ui").Command("tutorialmessage", "From this point forward, the Black Box Recorder will record all of your interaction with K-3D to the file you specified.");
  25. Application.CommandNode("/application/ui").Command("tutorialmessage", "You can stop recording at any time by simply closing the Black Box Recorder window ...");
  26. Application.CommandNode("/application/black_box_recorder/close").Command("activate", "");
  27. Application.CommandNode("/application/ui").Command("tutorialmessage", "Of course, the Black Box Recorder is only useful if it's running when a problem occurs ... that's why we've set it up so that, by default, the Black Box Recorder runs every time you start K-3D ...");
  28. Application.CommandNode("/application/window/tools_options").Command("activate", "");
  29. Application.CommandNode("/application/ui").Command("tutorialmessage", "You can toggle this feature on-and-off as you choose, although we hope you'll leave it on as a matter-of-habit ...");
  30. Application.CommandNode("/application/options/show_black_box_recorder").Command("highlight", "");
  31. Application.CommandNode("/application/ui").Command("tutorialmessage", "Note that when you let K-3D automatically start a Black Box Recorder for you in this way, it will write its log to your home directory, in the \".k3d/blackbox.log\" file ...");
  32. Application.CommandNode("/application/ui").Command("tutorialmessage", "... keep in mind that, each time you start K-3D, this file will be completely erased when recording begins.  So, if you encounter a problem, be sure to make a copy of the log file and post it to the K-3D bug database before you restart the program!");
  33. Application.CommandNode("/application/options/cancel").Command("activate", "");
  34. Application.CommandNode("/application/ui").Command("tutorialmessage", "Posting a bug to the K-3D bug database is easy ... you can follow the links from the K-3D home page, http://k3d.sourceforge.net, or you can go there directly at http://sourceforge.net/tracker/?group_id=11113&atid=111113 ...");
  35. Application.CommandNode("/application/ui").Command("tutorialmessage", "... follow the web-page instructions to submit a new bug, then upload your Black Box Recorder log as a file attachment, and you're done!  It's easy, and it's a valuable contribution to making K-3D the best-of-the-best in free-as-in-freedom 3D software.  Thanks in advance!");
  36. Application.CommandNode("/application/ui").Command("tutorialmessage", "We recommend you move-on to the \"Viewport Navigation\" tutorial next ...");
  37.  
  38. Application.CommandNode("/application/tutorial_message").Command("close", "");
  39. Application.CommandNode("/application/document/window/file_close").Command("activate", "");
  40. Application.CommandNode("/application/window/help_tutorials").Command("activate", "");
  41.